MediaIdle(IM: QC)

Inside Macintosh: QuickTime Components /

Chapter 10 - Derived Media Handler Components / Derived Media Handler Components Reference

Functions / Managing Your Media Handler Component

MediaIdle
The MediaIdle function allows the Movie Toolbox to provide processing time to your derived media handler during movie playback. Your media handler may use this time to play its media.
pascal ComponentResult MediaIdle (ComponentInstance ci, 
                                    TimeValue atMediaTime, 
                                    long flagsIn, long *flagsOut,
                                    const TimeRecord *movieTime);
ci
Identifies the Movie Toolbox's connection to your derived media handler.
atMediaTime

Specifies the current time, in your media's time base. You can use this time to determine the appropriate media data to work with.
flagsIn
Contains flags that indicate what the Movie Toolbox wants your media handler to do. These flags are applicable only to media handlers that perform their own scheduling.

The following flags are defined--the Movie Toolbox may use none, or it may set one or more flag to 1:
mMustDraw
Indicates that your media handler must play its media at this time. For graphical media, this means that your handler must draw the appropriate media data on the screen. For sound-based media, your handler must play the media's sounds. If this flag is set to 1, the Movie Toolbox has encountered a new sample in your media.
mAtEnd
Indicates that the current time corresponds to the end of the movie.
mPreflightDraw

Indicates that your media handler must not play its media at this time. Your handler may examine the media data and prepare to play it, but you should not draw any graphical data or play any sounds. If this flag is set to 1, your handler must not play its data.

If these flags are set to 0, then your media handler is free to decide whether to play the media data or not.
flagsOut
Contains a pointer to a long integer that your media handler uses to indicate to the Movie Toolbox what the handler did. You must always set the values of these flags appropriately.

The following flags are defined:
mDidDraw
Indicates that your media handler played its media's data with the handlerHasSpatial flag set, then it drew the data. Any time your media handler plays its media's data, you should set this flag to 1 when you return from your MediaIdle function. The Movie Toolbox uses this information when it is displaying a composited movie-- that is, a movie whose image is derived by blending several tracks together. If your media's track is obscured by other, semitransparent tracks, the Movie Toolbox must redraw those other tracks whenever your media's image changes.
mNeedsToDraw

Indicates that your media handler needs to play its data. Typically, you use this flag when the Movie Toolbox calls your MediaIdle function with the mPreflightDraw flag in the flagsIn field set to 1, and you discover that you have data that must be played at the current time. Set this flag to 1 if your handler needs to play its media's data.
movieTime
Contains a pointer to the movie time value corresponding to the atMediaTime parameter. Note that this may differ from the current value returned by the Movie Toolbox's GetMovieTime function.

DESCRIPTION
The Movie Toolbox uses your MediaIdle function to provide processing time to your derived media handler during movie playback. Your media handler is free to use this time in any appropriate manner. For example, if your media handler supports a sound data type, you might prepare to play your media's sounds or actually play them, depending upon the options asserted by the Movie Toolbox. Your media handler is responsible for limiting the amount of processing time it uses.
The Movie Toolbox provides the current time, in your media's time base, in the atMediaTime parameter. You can use this value to obtain the appropriate samples and sample descriptions from your media (using the Movie Toolbox's GetMediaSample function). Your media handler may then work with the sample data and descriptions as appropriate.
If you encounter an error, save the result code. The Movie Toolbox polls you for status information using the MediaGGetStatus function, which is described next.
Your handler should examine the flagsIn parameter each time the Movie Toolbox calls its MediaIdle function. The flags in this parameter indicate the actions that your handler may perform. In addition, when you return from your MediaIdle function, you should report what you did using the flagsOut parameter. You tell the base media handler that you perform your own scheduling by setting the handlerNoScheduler flag to 1 in the flags parameter of the MediaSetHandlerCapabilities function (see page 10-36 for more information about this function).
If your media handler changes any of the settings of the movie's graphics port or graphics world, be sure to restore the original settings before you exit. In addition, note that you may be drawing into a black-and-white graphics port. Finally, be aware that the Movie Toolbox also uses this function to obtain data for QuickDraw pictures. Therefore, if your media handler does not use QuickDraw when drawing to the screen, be sure to examine the picSave field in the graphics port so that you can detect when the toolbox wants to save an image. Your media handler is then responsible for performing the appropriate display processing. (For details on QuickDraw pictures, see the chapter "Basic QuickDraw" in Inside Macintosh: Imaging.)
Your derived media handler should support this function if you need to do work during movie playback. If you set the handlerNoIdle flag to 1 in the flags parameter of
the MediaSetHandlerCapabilities function, the Movie Toolbox does not call your MediaIdle function.

RESULT CODES
Any Component Manager result code